Windows development with Cygwin: a porting layer for UNIX applications

Contents|Index|Previous|Next
Windows development with Cygwin: a Win32 porting layer

CygwinTM, a full-featured Win32 porting layer for UNIX applications, is compatible with all Win32 hosts (currently, these are Microsoft’s Windows NT/95/98 systems).

The following documentation discusses porting the GNU development tools to the Win32 host while exploring the development and architecture of the Cygwin library.

- Porting UNIX tools to Win32
- Initial goals of Cygwin
- Compatibility issues with Cygwin
- Setting up Cygwin
- Using GCC with Cygwin
- Debugging Cygwin programs
- Building and using DLLs with Cygwin
- Defining Windows resources for Cygwin
- Cygwin utilities
- Cygwin functions

Cygwin was invented in 1995 by Cygnus as part of the answer to the question of how to port the GNU development tools to a Win32 host. The Win32-hosted GNUPro compiler tools that use the Cygwin library are available for a variety of embedded processors as well as a native version for writing Win32 applications.
By basing this technology on the GNU tools, Cygnus provides developers with a high-performance, feature-rich 32-bit code development environment, including a graphical source-level debugger, Cygnus InsightTM (see Working with Cygnus Insight, the visual debugger).

Cygwin is a dynamically-linked library (DLL) that provides a large subset of the system calls in common UNIX implementations. The current release includes all POSIX.1/90 calls except for `setuid` and `mkfifo`, all ANSI C standard calls, and many common BSD and SVR4 services (including Berkeley sockets). See also Compatibility issues with Cygwin.

When the Free Software Foundation (FSF) first wrote the GNU tools in the mid-1980s, portability among existing and future UNIX operating systems was an important goal. By mid-1995, the tools had been ported to 16-bit DOS using the GO32 32-bit extender by DJ Delorie (maintainer of the DJGPP Project; see `http://www.delorie.com/djgpp`). However, no one had completed a native 32-bit port for Windows NT and 95/98. It seemed likely that the demand for Win32-hosted native and cross-development tools would soon be large enough to justify the development costs involved. This project’s fulfillment and its ongoing challenges are testaments to the growth that Cygwin provides; for the individuals who have been responsible for creating the Cygwin porting layer; see Acknowledgements for Cygwin.

Porting UNIX tools to Win32

The first step in porting compiler tools to Win32 was to enhance them so that they could generate and interpret Win32 native object files, using Microsoft’s Portable Executable (PE) format. This proved to be relatively straightforward because of similarities to the Common Object File Format (COFF), which the GNU tools already supported. Most of these changes were confined to the Binary File Descriptor (BFD) library and to the linker.

In order to support the Win32 Application Programming Interface (API), we extended the capabilities of the binary utilities to handle Dynamic-Linked Libraries (DLLs). After creating export lists for the specific Win32 API DLLs that are shipped with Win32 hosts, the tools were able to generate static libraries that executables could use to gain access to Win32 API functions. Because of redistribution restrictions on Microsoft’s Win32 API header files, we wrote our own Win32 header files from scratch on an as-needed basis. Once this work was completed, we were able to build UNIX-hosted cross-compilers capable of generating valid PE executables that ran on Win32 systems. See also Using GCC with Cygwin.

The next task was to port the compiler tools themselves to Win32. Previous experiences using Microsoft Visual C++ to port GDB convinced us to find another means for bootstrapping the full set of tools. In addition to wanting to use our own compiler technology, we wanted a portable build system. The GNU development tools’configuration and build procedures require a large number of additional UNIX utilities not available on Win32 hosts. So we decided to use UNIX-hosted cross-compilers to build our Win32-hosted native and cross-development tools. It made perfect sense to do this since we were successfully using a nearly identical technique to build our DOS-hosted products.

The next obstacle to overcome was the many dependencies on UNIX system calls in the sources, especially in the GNU debugger GDB. While we could have rewritten sizable portions of the source code to work within the context of the Win32 API (as was done for the DOS-hosted tools), this would have been prohibitively time-consuming. Worse, we would have introduced conditionalized code that would have been expensive to maintain in the long run. Instead, Cygnus developers took a substantially different approach by writing Cygwin. See also Debugging Cygwin programs.

Initial goals of Cygwin

The following documentation discusses the work in developing the Cygwin tools.

- Harnessing the power of the web for Cygwin
- The Cygwin architecture
- Files and filetypes for Cygwin
- Text mode and binary bode interoperability with Cygwin
- ANSI C library for Cygwin
- Process creation for Cygwin
- Signals with Cygwin
- Sockets with Cygwin
- The select function with Cygwin
- Performance issues with Cygwin
- Ported software with Cygwin
- Future work for Cygwin
- Proprietary alternatives to Cygwin
- Acknowledgements for Cygwin

The original goal of Cygwin was simply to get the development tools working. Completeness with respect to POSIX.12 and other relevant UNIX standards was not a priority. Part of a definition of “working native tools” is having a build environment similar enough to UNIX to support rebuilding the tools themselves on the host system, a process we call self-hosting. The typical configuration procedure for a GNU tool involves running configure, a complex Bourne shell script that determines information about the host system. The script then uses that information to generate the Makefiles used to build the tool on the host in question.

This configuration mechanism is needed under UNIX because of the large number of varying versions of UNIX. If Microsoft continues to produce new variants of the Win32 API as it releases new versions of its operating systems, it may prove to be quite valuable on the Win32 host as well.

The need to support this configuration procedure added the requirement of supporting user tools such as `sh`, `make`, file utilities (such as `ls` and `rm`), text utilities (such as `cat`, `tr`), and shell utilities (such as `echo`, `date`, `uname`, `sed`, `awk`, `find`, `xargs`, `tar`, and `gzip`, among many others). Previously, most of these user tools had only been built natively (on the host on which they would run). As a result, we had to modify their `configure` scripts to be compatible with cross-compilation.

Other than making the necessary configuration changes, we wanted to avoid Win32-specific changes since the UNIX compatibility was to be provided by Cygwin as much as possible. While we knew this would be a sizable amount of work, there was more to gain than just achieving self-hosting of the tools. Supporting the configuration of the development tools would also provide an excellent method of testing the Cygwin library.

Although we were able to build working Win32-hosted toolchains with cross-compilers relatively soon after the birth of Cygwin, it took much longer than we expected before the tools could reliably rebuild themselves on the Win32 host because of the many complexities involved.

Harnessing the power of the web for Cygwin

Instead of keeping the Cygwin technology proprietary and developing it in-house, Cygnus chose to make it publicly available under the terms of the GNU General Public License (GPL), the traditional license for the GNU tools. Since its inception, we have made a new “GNU-Win32 beta release” available using ftp over the Internet every three or four months. Each release includes binaries of Cygwin and the development tools, coupled with the source code needed to build them. Unlike standard Cygnus products, these free releases come without any assurances of quality or support, although we provide a mailing list that is used for discussion and feedback.

In retrospect, making the technology freely available was a good decision because of the high demand for quality 32-bit native tools in the Win32 arena, as well as significant additional interest in a UNIX portability layer like Cygwin. While far from perfect, the beta releases are good enough for many people. They provide us with tens of thousands of interested developers who are willing to use and test the tools. A few of them are even willing to contribute code fixes and new functionality to the library. As of the last public release, developers on the Net had written or improved a significant portion of the library, including important aspects such as support for UNIX signals and the TTY/PTY calls.
In order to spur as much Net participation as possible, the Cygwin project features an open development model. Cygnus makes weekly source snapshots available to the general public in addition to the periodic full GNU-Win32 releases. A mailing lists for developers facilitates discussion of proposed changes to the library.

In addition to the GPL version of Cygwin, Cygnus provides a commercial license for supported customers of the native Win32 GNUPro tools.

The Cygwin architecture

The following documentation discusses the architecture underlying the Cygwin tools.

- Files and filetypes for Cygwin
- Text mode and binary bode interoperability with Cygwin
- ANSI C library for Cygwin

When a binary linked against the library is executed, the Cygwin DLL is loaded into the application’s text segment. Because we are trying to emulate a UNIX kernel that needs access to all processes running under it, the first Cygwin DLL to run creates shared memory areas that other processes using separate instances of the DLL can access. This is used to keep track of open file descriptors and assist fork and exec, among other purposes. In addition to the shared memory regions, every process also has a per-process structure that contains information such as process ID, user ID, signal masks, and other similar process-specific information.

The DLL is implemented using the Win32 API, allowing it to run on all Win32 hosts. Because processes run under the standard Win32 subsystem, they can access both the UNIX compatibility calls provided by Cygwin as well as any of the Win32 API calls. This gives the programmer complete flexibility in designing the structure of their program in terms of the APIs used. For example, a project might require a Win32-specific GUI using Win32 API calls on top of a UNIX back-end that uses Cygwin.

Early on in the development process, an important design decision was made to overcome the necessity to strictly adhere to existing UNIX standards like POSIX, if it was not possible or if it would significantly diminish the usability of the tools on the Win32 platform (ISO/IEC 9945-1:1996 [ANSI/IEEE Std 1003.1, 1996 Edition]; POSIX Part 1: System Application Program Interface [API/C Language]). In many cases, an environment variable can be set to override the default behavior and force standards compliance.

While Windows 95 and Windows 98 are similar enough to each other that developers can safely ignore the distinction when implementing Cygwin, Windows NT is an extremely different operating system. For this reason, whenever the DLL is loaded, the library checks which operating system is active so that it can act accordingly. In some cases, the Win32 API is only different for historical reasons. In this situation, the same basic functionality is available under 95/98 and NT, although the method used to gain this functionality differs. A trivial example is in our implementation of uname, the library examines the sysinfo.wProcessorLevel structure member to determine the processor type used for Windows 95/98. This field is not supported in NT, which has its own operating system-specific structure member called sysinfo.wProcessorLevel.

Other differences between NT and 95/98 are much more fundamental in nature. The best example is that only NT provides a security model.

Windows NT includes a sophisticated security model based on Access Control Lists (ACLs). Although some modern UNIX operating systems include support for ACLs, Cygwin maps Win32 file ownership and permissions to the more standard, older UNIX model. The `chmod` call maps UNIX-style permissions back to the Win32 equivalents. Because many programs expect to be able to find the `/etc/passwd` and `/etc/group` files, we provide utilities that can be used to construct them from the user and group information provided by the operating system.

Under Windows NT, the administrator is permitted to chown files. There is currently no mechanism to support the `setuid` concept or API call. Although Cygnus hopes to support this functionality at some point in the future, in practice, the programs that have ported have not needed it.

Under Windows 95/98, the situation is considerably different. Since a security model is not provided, Cygwin fakes file ownership by making all files look like they are owned by a default user and group ID. As under NT, file permissions can still be determined by examining their read/write/execute status. Rather than return an unimplemented error, under Windows 95/98, the `chown` call succeeds immediately without actually performing any action. This is appropriate since essentially all users jointly own the files when no concept of file ownership exists.

It is important that we discuss the implications of our kernel, using shared memory areas to store information about Cygwin processes. Because these areas are not yet protected in any way, a malicious user could perhaps modify them to cause unexpected behavior in Cygwin processes. While this is not a new problem under Windows 95/98 (because of the lack of operating system security), it does constitute a security hole under Windows NT. This is because one user could affect the Cygwin programs run by another user by changing the shared memory information in ways that they could not in a more typical WinNT program. For this reason, it is not appropriate to use Cygwin in high-security applications. In practice, this will not be a major problem for most uses of the library.

Files and filetypes for Cygwin

Cygwin supports both Win32- and POSIX-style paths, using either forward or back slashes as the directory delimiter. Paths coming into the DLL are translated from Win32 to POSIX as needed. As a result, the library believes that the file system is a POSIX-compliant one, translating paths back to Win32 paths whenever it calls a Win32 API function. UNC pathnames (Universal Naming Conventions, which are paths that start with two slashes) are supported. See also Cygwin’s compatibility with POSIX.1 standards.

The layout of this POSIX view of the Windows file system space is stored in the Windows registry. While the slash (‘`/`’) directory points to the system partition by default, this is easy to change with the Cygwin mount utility. In addition to selecting the slash partition, it allows mounting arbitrary Win32 paths into the POSIX file system space. Many people use the utility to mount each drive letter under the slash partition (that is, `C:\` to`/c`, `D:\` to `/d`, and so forth).

The library exports several Cygwin-specific functions that can be used by external programs to convert a path or path list from Win32 toPOSIX or vice versa. Shell scripts and Makefiles cannot call these functions directly. Instead, they can do the same path translations by executing the `cygpath` utility.

Win32 file systems are case preserving but case insensitive. Cygwin does not currently support case distinction because, in practice, few UNIX programs actually rely on it. While we could mangle file names to support case distinction, this would add unnecessary overhead to the library and make it more difficult for non-Cygwin applications to access those files.

Symbolic links are emulated by files containing a magic cookie followed by the path to which the link points. They are marked with the System attribute so that only files with that attribute have to be read to determine whether or not the file is a symbolic link. Hard links are fully supported under Windows NT on NTFS file systems. On a FAT file system, the call falls back to copying the file, a strategy that works in many cases.

The `inode` number for a file is calculated by hashing its full Win32 path. The `inode` number generated by the stat call always matches the one returned in `d_ino` of the dirent structure. It is worth noting that the number produced by this method is not guaranteed to be unique. However, we have not found this to be a significant problem because of the low probability of generating a duplicate inode number.

Text mode and binary bode interoperability with Cygwin

Interoperability with other Win32 programs such as text editors was critical to the success of the port of the development tools. Most Cygnus customers upgrading from the older DOS-hosted toolchains expected the new Win32-hosted ones to continue to work with their old development sources.

Since UNIX and Win32 use different end-of-line terminators in text files, consequently, carriage-return newlines have to be translated by Cygwin into a single newline when reading in text mode. The Ctrl+z character is interpreted as a valid end-of-file character for a similar reason.

This solution addresses the compatibility requirement at the expense of violating the POSIX standard that states that text and binary mode will be identical. Consequently, processes that attempt to lseek through text files can no longer rely on the number of bytes read as an accurate indicator of position in the file. For this reason, an environment variable can be set to override this behavior. See also Cygwin’s compatibility with POSIX.1 standards, Environment variables for Cygwin and Text and binary modes.

ANSI C library for Cygwin

We chose to include Cygnus’ own existing ANSI C library, `newlib` (ISO/IEC 9899:1990, Programming Languages [C]), as part of the library, rather than write all of the GNU C libraries and math calls from scratch. `newlib` is a BSD-derived ANSI C library, previously only used by cross-compilers for embedded systems development.

The reuse of existing free implementations of such things as the `glob`, `regexp`, and `getopt` libraries saved considerable effort. In addition, Cygwin uses Doug Lea’s free `malloc` implementation that successfully balances speed and compactness. The library accesses the `malloc` calls, using an exported function pointer. This makes it possible for a Cygwin process to provide its own `malloc` if required.

For more information, see Cygwin’s compatibility with ANSI standards.

Process creation for Cygwin

The following documentation discusses the process in the API with Cygwin tools.

- Signals with Cygwin
- Sockets with Cygwin
- The select function with Cygwin
- Performance issues with Cygwin
- Ported software with Cygwin

The `fork` call in Cygwin is particularly interesting because it does not map well on top of the Win32 API. This makes it very difficult to implement. Currently, the Cygwin fork is a non-copy-on-write implementation similar to what was present in early versions of UNIX.

The first thing that happens when a parent process forks a child process is that the parent initializes a space in the Cygwin process table for the child. It then creates a suspended child process using the Win32 CreateProcess call. Next, the parent process calls `setjmp` to save its own context and sets a pointer to this in a Cygwin shared memory area (shared among all Cygwin tasks). It then fills in the child’s `.data` and `.bss` sections by copying from its own address space into the suspended child’s address space. After the child’s address space is initialized, the child is run while the parent waits on a `mutex`. The child discovers it has been forked and longjumps using the saved jump buffer. The child then sets the mutex the parent is waiting on and blocks on another mutex. This is the signal for the parent to copy its stack and heap into the child, after which it releases the mutex the child is waiting on and returns from the fork call. Finally, the child wakes from blocking on the last mutex, recreates any memory-mapped areas passed to it from the shared area, and returns from fork itself.

While we have some ideas as to how to speed up our `fork` implementation by reducing the number of context switches between the parent and child process, fork will almost certainly always be inefficient under Win32. Fortunately, in most circumstances, the spawn family of calls provided by Cygwin can be substituted for a `fork/exec` pair with only a little effort. These calls map cleanly on top of the Win32 API. As a result, they are much more efficient. Changing the compiler’s driver program to call spawn instead of fork was a trivial change and increased compilation speeds by 20-30% in our tests.

However, `spawn` and `exec` present their own set of difficulties. Because there is no way to do an actual `exec` under Win32, Cygwin has to invent its own Process IDs (PIDs). As a result, when a process performs multiple `exec` calls, there will be multiple Windows PIDs associated with a single Cygwin PID. In some cases, stubs of each of these Win32 processes may linger, waiting for their Cygwin process to exit.

Signals with Cygwin

When a Cygwin process starts, the library starts a secondary thread for use in signal handling. This thread waits for Windows events used to pass signals to the process. When a process notices it has a signal, it scans its signal bitmask and handles the signal in the appropriate fashion.

Several complications in the implementation arise from the fact that the signal handler operates in the same address space as the executing program. The immediate consequence is that Cygwin system functions are interruptible unless special care is taken to avoid this. We go to some lengths to prevent the `sig_send` function that sends signals from being interrupted. In the case of a process sending a signal to another process, we place a mutex around `sig_send` such that `sig_send` will not be interrupted until it has completely finished sending the signal.
In the case of a process sending itself a signal, we use a separate semaphore/event pair instead of the `mutex`. `sig_send` starts by reset
ting the event and incrementing the semaphore that flags the signal handler to process the signal. After the signal is processed, the signal handler signals the event that it is done. This process keeps intraprocess signals synchronous, as required by POSIX. Most standard UNIX signals are provided. Job control works as expected in shells that support it.

Sockets with Cygwin

Socket-related calls in Cygwin simply call the functions by the same name in Winsock, Microsoft’s implementation of Berkeley sockets. Only a few changes were needed to match the expected UNIX semantics; one of the most troublesome differences was that Winsock must be initialized before the first socket function is called. As a result, Cygwin has to perform this initialization when appropriate. In order to support sockets across fork calls, child processes initialize Winsock if any inherited file descriptor is a socket.

Unfortunately, implicitly loading DLLs at process startup is usually a slow affair. Because many processes do not use sockets, Cygwin explicitly loads the Winsock DLL the first time it calls the Winsock initialization routine. This single change sped up GNU configure times by 30%.

The `select` function with Cygwin

The UNIX `select` function is another call that does not map cleanly on top of the Win32 API. Much to our dismay, we discovered that the Win32 `select` in Winsock only worked on socket handles. Our implementation allows `select` to function normally when given different types of file descriptors (such as sockets, pipes, handles, and a custom /dev/windows windows messages pseudo-device).

Upon entry into the `select` function, the first operation is to sort the file descriptors into the different types. There are then two cases to consider.

- The simple case is when at least one file descriptor is a type that is always known to be ready (such as a disk file). In that case, select returns immediately as soon as it has polled each of the other types to see if they are ready.

- The more complex case involves waiting for socket or pipe file descriptors to be ready. This is accomplished by the main thread suspending itself, after starting one thread for each type of file descriptor present. Each thread polls the file descriptors of its respective type with the appropriate Win32 API call. As soon as a thread identifies a ready descriptor, that thread signals the main thread to wake up. This case is now the same as the first one since we know at least one descriptor is ready. So `select` returns, after polling all of the file descriptors one last time.

Performance issues with Cygwin

Early on in the development process, correctness was almost the entire emphasis and, as Cygwin became more complete, performance became a much important issue. It was known that the tools ran much more slowly under Win32 than under Linux on the same machine, but it was not clear at all whether to attribute this to differences in the operating systems or to inefficiencies in Cygwin.
The lack of a working profiler has made analyzing Cygwin’s performance particularly difficult. Although the latest version of the library includes real itimer support, we have not yet found a way to implement virtual itimers. This is the most reliable way of obtaining profiling data since concurrently running processes aren’t likely to skew the results. We will soon have a combination of the GCC compiler and the GNU profile analysis tool, `gprof`, working with real itimer support which will help a great deal in optimizing Cygwin.

Even without a profiler, we knew of several areas inside Cygwin that definitely needed a fresh approach. While we rewrote those sections of code, we used the speed of configuring the tools under Win32 as the primary performance measurement. This choice made sense because we knew process creation speed was especially poor, something that the GNU `configure` process stresses.

These performance adjustments made it possible to configure completely the development tools under NT with Cygwin in only 10 minutes and complete the build in just under an hour on a dual Pentium Pro 200 system with 128 MB of RAM. This is reasonably competitive with the time taken to complete this task under a typical UNIX operating system running on an identical machine.

Ported software with Cygwin

In addition to being able to configure and build most GNU software, several other significant packages have been successfully ported to the Win32 host using the Cygwin library. Following is a list of some of the more interesting ones (most are not included in the distributions):

- X11R6 client libraries, enabling porting many X programs to the existing free Win32 X servers (examples of successfully ported X applications include `xterm`, `ghostview`, `xfig`, and `xconq`)
- `xemacs` and `vim` editors
- GNU inetutils in order to run the `inetd` daemon as a Windows NT service to enable UNIX-style networking, using a custom NT login binary to allow remote logins with full user authentication; one can achieve similar results under Windows 95/98 by running `inetd` out of the autoexec.bat file, providing a custom 95/98-tailored login binary
- KerbNet, the implementation by Cygnus of the Kerberos security system
- CVS (Concurrent Versions System), a popular version control program based on RCS; Cygnus uses a Kerberos-enabled version of CVS to grant secure access to GNU source code for local and remote engineers
- `ncurses`, a library that can be used to build a functioning version of the pager
- `ssh` (secure shell) client and server
- PERL 5 scripting language
- `bash`, `tcsh`, `ash`, and `zsh` shells; full job control is available in shells that support it
- Apache web server (some source-level changes were necessary)
- Tcl/Tk 8; also `tix`, `[itcl]`, and `expect` (Tcl/Tk needed non-trivial configuration changes)

Typically, the only necessary source code modification involves specifying binary mode to open calls as appropriate. Because the Win32 compiler always generates executables that end in the standard .exe suffix, it is also often necessary to make minor modifications to makefiles so that `make` will expect the newly built executables to end with the suffix.

Future work for Cygwin

Standards conformance is becoming a more important focus. Previous work includes getting all POSIX.1/90 calls implemented; except for `mkfifo` and `setuid`, they have been. X/Open Release 4 conformance ( see the X/Open Release 4 CAE Specification, System Interfaces and Headers, Issue 4, Vol. 2, X/Open Co, Ltd., 1994) may be a desirable goal, but it is not yet implemented. While the current version of the library passes most of the NIST POSIX test suite (NIST POSIX test suite; see `http://www.itl.nist.gov/div897/ctg/posix_form.htm`), it performs poorly with respect to mimicking the UNIX security model, so there is still room for improvement. When considering how to implement the setuid functionality, there must be a secure alternative to the library’s usage of the shared memory areas.

Cygwin does not yet support applications that use multiple Windows threads, even though the library itself is multi-threaded. This shortcoming through the use of locks at strategic points in the DLL is desired, as well as creating support for POSIX threads.

Although Cygwin allows the GNU development tools that depend heavily on UNIX semantics to run successfully on Win32 hosts, it is not always desirable to use it. A program using a perfect implementation of the library would still incur a noticeable amount of overhead. As a result, an important future direction involves modifying the compiler so that it can optionally link against the Microsoft DLLs that ship with both Win32 operating systems, instead of Cygwin. This will give developers the ability to choose whether or not to use Cygwin on a per-program basis.

Proprietary alternatives to Cygwin

In developing Cygwin, alternatives to writing a library either did not exist or were not mature enough for the intended purposes.

Today, there are three proprietary alternatives to Cygwin, as the following documentation describes.

- UWIN (“UNIX for Windows,” and see UNIX for Windows by Korn, David G., originally from proceedings of the 1997 USENIX Windows NT Annual Technical Conference), as developed by David Korn for AT&T Laboratories. Its architecture and API appears to be quite similar to the Cygwin library. Its single biggest advantage over Cygwin is probably its more complete support for the UNIX security model. UWIN binaries are available for free non-commercial use, but its source code is not available.

- NuTCracker, by DataFocus, another proprietary product that is built on top of the Win32 subsystem. Version 4.0 of the product appears to be quite complete, including such features as support for POSIX threads.

- OpenNT from Softway Systems (OpenNT: UNIX Application Portability to Windows NT via an Alternative Environment Subsystem; Walli, Stephen R., originally from the 1997 USENIX Windows NT Workshop Proceedings)

However, there are two substantial drawbacks to OpenNT’s approach. The first is that it is not possible to mix UNIX and Win32 API calls in one application, a feature that is highly desirable when trying to do a full native Win32 port of a UNIX program gradually, one module at a time. The second drawback is that OpenNT does not and cannot support Windows 95/98, a requirement for many applications, including the GNUPro development tools.

The lack of source code, coupled with the licensing fees associated with each of these commercial offerings, might still have required writing a library if there was the same challenge of porting today.

Acknowledgments for Cygwin

There are many individuals who helped create Cygwin: Steve Chamberlain (who wrote the original implementation of the library), Jeremy Allison, Doug Evans, Christopher Faylor, Philippe Giacinti, Tim Newsham, Sergey Okhapkin, Ian Taylor, Eric Bachalo, Chip Chapin, Kathleen Jones, Robert Richardson, Stan Shebs, Sonya Smallets, Ethan Solomita, and Stephan Walli.

### Compatibility issues with Cygwin

The following documentation discuses the compatibility issues with Cygwin porting layer tools and the Cygwin library and its functionality.

- Cygwin’s compatibility with ANSI standards
- Cygwin’s compatibility with POSIX.1 standards
- Cygwin’s compatibility with other miscellaneous standards

#### Cygwin’s compatibility with ANSI standards

The following functions are compatible with ANSI standards.

- `stdio` functions
`clearerr`, `fclose`, `feof`, `ferror`, `fflush`, `fgetc`, `fgetpos`, `fgets`, `fopen` , `fprintf`, `fputc`, `fputs`, `fread`, `freopen`, `fscanf`, `fseek`, `fsetpos` , `ftell`, `fwrite`, `getc`, `getchar`, `gets`, `perror`, `printf`, `putc`, `putchar` , `puts`, `remove`, `rename`, `rewind`, `scanf`, `setbuf`, `setvbuf`, `sprintf`, `sscanf`, `tmpfile`, `tmpnam`, `vfprintf`, `ungetc`, `vprintf`, `vsprintf`.
- `string` functions
`memchr`, `memcmp`, `memcpy`, `memmove`, `memset`, `strcat`, `strchr` , `strcmp`, `strcoll`, `strcpy`, `strcspn` , `strerror`, `strlen`, `strncat`, `strncmp` , `strncpy`, `strpbrk`, `strrchr`, `strspn` , `strstr`, `strtok`, `strxfrm`.
- `stdlib` functions
`abort`, `abs`, `assert`, `atexit` , `atof`, `atoi`, `atol`, `bsearch`, `calloc`, `div`, `exit`, `free`, `getenv`, `labs` , `ldiv`, `longjmp`, `malloc`, `mblen`, `mbstowcs`, `mbtowc`, `qsort`, `rand`, `realloc`, `setjmp`, `srand`, `strtod`, `strtol`, `strtoul`, `system`, `wcstombs` , `wctomb`.
- `time` functions
`asctime`, `gmtime`, `localtime` , `time`, `clock`, `ctime`, `difftime`, `mktime`, `strftime`.
- `signals` functions
`raise`, `signal`.
- `ctype` functions
`isalnum`, `isalpha`, `iscntrl` , `isdigit`, `isgraph`, `islower`, `isprint`, `ispunct`, `isspace`, `isupper`, `isxdigit`, `tolower`, `toupper`.
- `math` functions
`acos`, `asin`, `atan`, `atan2` , `ceil`, `cos`, `cosh`, `exp`, `fabs` , `floor`, `fmod`, `frexp`, `ldexp`, `log` , `log10`, `modf`, `pow`, `sin`, `sinh`, `sqrt`, `tan`, `tanh`.
- Miscellaneous functions
`localeconv`, `setlocale`, `va_arg` , `va_end`, `va_start`.

#### Cygwin’s compatibility with POSIX.1 standards

The following functions are compatible with POSIX.1.

- Process primitives
`fork`, `execl`, `execle`, `execlp` , `execv`, `execve`, `execvp`, `wait`, `waitpid`, `_exit`, `kill`, `sigemptyset` , `sigfillset`, `sigaddset`, `sigdelset`, `sigismember` , `sigaction`, `pthread_sigmask`, `sigprocmask`, `sigpending`, `sigsuspend`, `alarm`, `pause`, `sleep`.
- Process environment
`getpid`, `getppid`, `getuid` , `geteuid`, `getgid`, `getegid`, `setuid`, `setgid`, `getgroups`, `getlogin`, `getpgrp` , `setsid`, `setpgid`, `uname`, `time`, `times`, `getenv`, `ctermid`, `ttyname`, `isatty`, `sysconf`.
- Files and directories
`opendir`, `readdir`, `rewinddir` , `closedir`, `chdir`, `getcwd`, `open`, `creat`, `umask`, `link`, `mkdir`, `unlink` , `rmdir`, `rename`, `stat`, `fstat`, `access`, `chmod`, `fchmod`, `chown`, `utime`, `ftruncate`, `pathconf`, `fpathconf`.
- Input and output primitives
`pipe`, `dup`, `dup2`, `close`, `read`, `write`, `fcntl`, `lseek`, `fsync`.
- Device-specific and class-specific functions
`cfgetispeed`, `cfgetospeed`, `cfsetispeed` , `cfsetospeed`, `tcdrain`, `tcflow`, `tcflush` , `tcgetattr`, `tcgetpgrp`, `tcsendbreak`, `tcsetattr`, `csetpgrp`.
- Language-specific services for the C programming language
`abort`, `exit`, `fclose`, `fdopen` , `fflush`, `fgetc`, `fgets`, `fileno`, `fopen`, `fprintf`, `fputc`, `fputs`, `fread` , `freopen`, `fscanf`, `fseek`, `ftell` , `fwrite`, `getc`, `getchar`, `gets`, `perror`, `printf`, `putc`, `putchar`, `puts`, `remove`, `rewind`, `scanf`, `setlocale` , `siglongjmp`, `sigsetjmp`, `tmpfile`, `tmpnam`, `tzset`.
- System databases
`getgrgid`, `getgrnam`, `getpwnam`, `getpwuid`.
- Memory management
`mmap`, `mprotect`, `msync`, `munmap`.

`setuid` and `setgid` always return `ENOSYS`.
`link` will copy the file if it can’t implement a true symbolic link. Currently, symbolic links work, if at all, only under Windows NT.
`chown` always returns 0.
`fcntl` doesn’t support `F_GETLK` ; it returns `-1` and sets `errno` to `ENOSYS`.
`lseek` only works properly on binary files.

#### Cygwin’s compatibility with other miscellaneous standards

The following functions are compatible with miscellaneous other standards.

- Networking functions
(standardized by POSIX 1.g, still in draft)
`accept`, `bind`, `connect`, `getdomainname`, `gethostbyaddr`, `gethostbyname`, `getpeername` , `getprotobyname`, `getprotobynumber`, `getservbyname`, `getservbyport`, `getsockname`, `getsockopt`, `herror`, `htonl`, `htons`, `inet_addr`, `inet_makeaddr`, `inet_netof`, `inet_ntoa`, `listen` , `ntohl`, `ntohs`, `rcmd`, `recv`, `recvfrom` , `rexec`, `rresvport`, `send`, `sendto`, `setsockopt`, `shutdown`, `socket`, `socketpair`.

> Of these networking calls, `rexec`, `rcmd` and `rresvport` are implemented in MS IP stack but may not be implemented in other vendor stacks.

- Other functions
`chroot`, `closelog`, `cwait`, `dlclose`, `dlerror`, `dlfork`, `dlopen`, `dlsym` , `endgrent`, `ffs`, `fstatfs`, `ftime` , `get_osfhandle`, `getdtablesize`, `getgrent`, `gethostname`, `getitimer`, `getmntent`, `getpagesize` , `getpgid`, `getpwent`, `gettimeofday`, `grantpt` , `initgroups`, `ioctl`, `killpg`, `login` , `logout`, `lstat`, `mknod`, `memccpy` , `nice`, `openlog`, `pclose`, `popen`, `ptsname`, `putenv`, `random`, `readv`, `realpath`, `regfree`, `rexec`, `select` , `setegi`, `setenv`, `seterrno`, `seteuid` , `setitimer`, `setmntent`, `setmode`, `setpassent` , `setpgrp`, `setpwent`, `settimeofday`, `sexecl` , `sexecle`, `sexeclp`, `sexeclpe`, `sexeclpe` , `sexecp`, `sexecv`, `sexecve`, `sexecvpe` , `sigpause`, `spawnl`, `spawnle`, `spawnlp` , `spawnlpe`, `spawnv`, `spawnve`, `spawnvp` , `spawnvpe`, `srandom`, `statfs`, `strsignal` , `strtosigno`, `swab`, `syslog`, `timezone` , `truncate`, `ttyslot`, `unlockpt`, `unsetenv` , `usleep`, `utimes`, `vfork`, `vhangup` , `wait3`, `wait4`, `wcscmp`, `wcslen`, `wprintf`, `writev`.

`initgroups` does nothing.
`chroot`, `mknod`, `settimeofday`, and `vhangup` always return `-1` and sets `errno` to `ENOSYS`.
`seteuid`, `setegid` , and `settimeofday` always return `0` and sets `errno` to `ENOSYS` .
`vfork` just calls `fork`.

### Setting up Cygwin

The following documentation discusses setting up the Cygwin tools.

- Installing the binary release for Cygwin
- Directory structure for Cygwin
- Environment variables for Cygwin
- Mount table

The following packages are included in the native Win32 release of GNUPro.

- GNUPro development tools
`binutils`, `bison`, `byacc`, `dejagnu` , `diff`, `expect`, `flex`, `gas`, `gcc`, `gdb`, `itcl`, `ld`, `libstdc++`, `make` , `patch`, `tcl`, `tix`, `tk`.
- GNUPro unsupported tools
`ash`, `bash`, `bzip2`, `diff`, `fileutils` , `findutils`, `gawk`, `grep`, `gzip`, `m4`, `sed`, `shellutils`, `tar`, `textutils`, `time`.

#### Installing the binary release for Cygwin

The following procedures help when installing the binaries for the Cygwin tools.

###### NOTE:

This is not necessary unless your process begins with re-installing the GNUPro tools.

1.
Load the GNUPro CD-ROM and run the installer.

> The installation process starts by asking for your install location. Once the installation is complete, there will be a new Program Files folder that you can use to obtain a shell from which you can run the tools.

2.
Ensure that the ‘temp’ directory is in the proper place.

> Type `mkdir -p /tmp` to ensure that a ‘temp’ directory exists for programs that you expect to find one there.

3.
Depending on how you intend to use the tools, various programs may need to be able to find ‘`/bin/sh`’ directory path.

> Use the ‘`mkdir -p /bin`’ declaration and put a copy of ‘sh.exe’ file there, removing the older version, if present. Use the ‘`mount`’ utility to specify a drive.

> If you should ever want to uninstall the tools, you may do so with “Add/Remove Programs” (accessed from the Start button’s Settings selection for Control Panel).

#### Directory structure for Cygwin

Cygwin knows how to emulate a standard UNIX directory structure, to some extent. You should make sure that you always have /tmp both with and without the `mount` table translations, just in case. If you want to emulate the `/etc` directory (so that the UNIX declaration,`ls -l`, works), use the following example’s declarations as a guide.

>     mkdir /etc/

>     cd /etc

>     mkpasswd > /etc/passwd

>     mkgroup > /etc/group

###### NOTE:

This only works fully under Windows NT. Under Windows 9 x, you may need to edit these files with a text editor. Further changes to your NT registry will not be reflected in `/etc/passwd` or`/etc/group` after this implementation, so you may want to regenerate these files periodically. You should also set your home directories to something other than ‘/’ to prevent unexplained delays in various programs.

#### Environment variables for Cygwin

`make` uses an environment variable, `MAKE_MODE`, to decide if it uses Command.com or `/bin/sh` to run command lines. If you’re getting strange errors from make with the message,`/c not found`, set `MAKE_MODE` to `UNIX` with a declaration like the following example’s form.

>     C:\> set MAKE_MODE=UNIX

>     $ export MAKE_MODE=UNIX

The `HOME` environment variable is used by UNIX shells to determine the location of your home directory. This environment variable is converted from Windows format (that is, C:\home\bob) to UNIX format (that is, `/home/bob`) when a Cygwin process first starts.
The `PATH` environment variable is used by Cygwin applications as a list of directories to search for executable files to run. This environment variable is converted from Windows format (that is, C:\WinNT\system32;C:\WinNT) to UNIX format (that is, `/WinNT/system32:/WinNT` ) when a Cygwin process first starts.
The `LD_LIBRARY_PATH` environment variable is used by the Cygwin function, `dlopen ()`, as a list of directories to search for .dll files to load. This environment variable is converted from Windows format (that is, C:\WinNT\system32;C:\WinNT) to UNIX format (that is, `/WinNT/system32:/WinNT`) when a Cygwin process first starts.
The most important environment variable is the `CYGWIN` variable. It is used to configure many global settings for the Cygwin runtime system. It allows you to express many attributes, using a syntax like the following declaration.

>     set CYGWIN="foo nobar grill=27"

###### NOTE:

Each option is separated by others with a space. Many options can be turned off by prefixing with “`no`” (such as “`nobar`” or “`bar`” options). The following options are available.

- `(no)export`
If set, the final values of these settings are re-exported to the environment as `$CYGWIN` again.
- `(no)title`
If set, the title bar reflects the currently running program’s name. Off by default.
- `(no)strip_title`
If set, strips the directory part off the window title. Off by default.
- `(no)glob`
If set, command line arguments containing UNIX-style file wildcard characters (brackets, question mark, asterisk) are expanded into lists of files that match those wildcards. This is applicable only to programs running from a windows command line prompt. Set by default.
- `(no)tty`
If set, Cygwin enables extra support (such as termios) for UNIX-like tty calls. Off by default.
- `(no)binmode`
If set, pipes and unspecified file opens default to binary mode (no CR/LF/Ctrl-Z translations) instead of text mode. Defaults to text mode.
- `strace=n[:cache][,filename]`
Configures system tracing. Off by default, setting various bits in n (a bit flag) enables various types of system messages. Setting n to 1 enables most messages. Other values can be found in `sys/strace.h` . The `:cache` option lets you specify how many lines to cache before flushing the output; as an example, `strace=1:20` . The `filename` option lets you send the messages to a file instead of the screen.
- `(no)ntea`
If set, use the full NT Extended Attributes to store UNIX-like inode information.

###### Warning:

This may create additional large files on non-NTFS partitions. This option only operates under Windows NT. Off by default.

- `(no)reset_com`
If set, serial ports are reset to 9600-8-N-1 with no flow control when used. This is done at open time and when handles are inherited. Set by default.
- `(no)envcache`
If set, environment variable conversions (between Win32 and POSIX) are cached. This is may cause problems if the `mount` table changes, as the cache is not invalidated and may contain values that depend on the previous mount table contents. Set by default.

#### Mount table

The `mount` utility controls a mount table that is used to emulate a POSIX view of the Windows file system space. This can be used to change the Windows path used as ‘/’and mount arbitrary Win32 paths into the POSIX file system space. Many people use the utility to mount each drive letter under the slash partition (such as C:\ to `/c` or D:\ to `/d`, and so forth).
Executing `mount` without any arguments prints the current mount table to the screen. Otherwise, provide the Win32 path you would like to mount as the first argument and the POSIX path as the second argument.
The following example demonstrates using the `mount` utility to mount the “C:/Cygnus/b20/H-i586-cygwin32/bin” directory to the “`/bin`” folder. This makes `/bin/sh` a valid shell, to satisfy `make`.
`C:\cygnus\> ls /bin`

`ls: /bin: No such file or directory`
`C:\cygnus\> mkdir /bin`
`C:\cygnus\> mount`
`C:/Cygnus/b20/H-i586-cygwin32/bin /bin`
`C:\cygnus\> mount`
`Device Directory Type Flags`
`C: /c native text!=binary`
`D: /d native text!=binary`
`\\.\tape1: /dev/st1 native text!=binary`
`\\.\tape0: /dev/st0 native text!=binary`
`\\.\b: /dev/fd1 native text!=binary`
`\\.\a: /dev/fd0 native text!=binary`
`C:\Cygnus\b20\H-i586-cygwin32\bin /bin native text!=binary`
`C: / native text!=binary`
`C:\cygnus\> ls /bin/sh`
`/bin/sh`
`C:\cygnus\>`

The `mount` table is stored in the Windows registry (HKEY_CURRENT_USER/Cygnus Solutions/CYGWIN DLL setup/<version>/mounts) where <version> is the latest registry version associated with the Cygwin library.

### Using GCC with Cygwin

The following documentation discusses using the GNUPro compiler, GCC, with Cygwin.

- Console mode applications
- GUI mode applications

#### Console mode applications

Use GCC to compile, just like under UNIX. See Using GNU CC in the GNUPro Compiler Tools documentation for information on standard usage and options. The following example shows the usage practice for the shell’s console.
`C:\cygnus\>` gcc hello.c -o hello.exe

`C:\cygnus\>` hello.exe
`Hello, World`

`C:\cygnus\>`

#### GUI mode applications

Cygwin allows you to build programs with full access to the standard Windows 32-bit API, including the GUI functions as defined in any Microsoft or off-the-shelf publication. However, the process of building those applications is slightly different, as you’ll be using the GNU tools instead of the Microsoft tools.
For the most part, your sources won’t need to change at all. However, you should remove all `__export` attributes from functions and replace them. The following example’s script shows such implementation.

>     int foo (int) __attribute__ ((__dllexport__));

>     int

>     foo (int i)

For most cases, you can just remove the `__export` attributes. For convenience sake, you might want to work around a misfeature in Cygwin’s libraries by including the following code fragment; otherwise, you’ll have to add a “`-e _mainCRTStartup`” declaration to your link line in your Makefile.

> `#ifdef __CYGWIN__`

>     WinMainCRTStartup() { mainCRTStartup(); }

> `#endif`

The Makefile is similar to any other UNIX-like Makefile, and any other Cygwin Makefile. The only difference is that you use a “`gcc -mwindows`” declaration to link your program into a GUI application instead of a command-line application. The following example’s script shows such implementation:

>     myapp.exe : myapp.o myapp.res

>            gcc -mwindows myapp.o myapp.res -o $@

>     myapp.res : myapp.rc resource.h

>            windres $< -O coff -o $@

###### NOTE:

The use of `windres` is for compiling the Windows resources into a COFF-format `.res` file. That will include all the bitmaps, icons, and other resources you need, into one handy object file. Normally, if you omitted the “`-O coff`” declaration, it would create a Windows `.res` format file, but we can only link COFF objects. So, we tell `windres` to produce a COFF object, but for compatibility with the many examples that assume your linker can handle Windows resource files directly, we maintain the`.res` naming convention. For more information on `windres`, see Using `binutils` in the GNUPro Utilities documentation.

### Debugging Cygwin programs

When your programs don’t work properly, they usually have bugs (meaning there’s something wrong with the program itself that is causing unexpected results or crashes). Diagnosing these bugs and fixing them is made easy by special tools called debuggers. In the case of Cygwin, the debugger is GDB, the GNU debugger, a tool lets you run your program in a controlled environment so that you can investigate the state of your program while it is running or after it crashes.
Before you can debug your program, you need to prepare your program for debugging. Add a ‘`-g`’ declaration to all the other flags you use when compiling your sources to objects. Consider the following example’s declarations.

>     gcc -g -O2 -c myapp.c

>     gcc -g myapp.c -o myapp

What this does is add extra information to the objects (making them much bigger), telling the debugger about line numbers, variable names, and other useful things. These extra symbols and debugging data give your program enough information about the original sources so that the debugger can make debugging much easier for you.
GDB is a command-line tool. To invoke it, use the ‘`gdb myapp.exe`’ declaration (substituting the executable file’s name for `myapp` ) at the command prompt. Some text then displays about general usage agreements, then the prompt, `(gdb)`, will appear to prompt you to enter commands. Whenever you see this prompt, it means that GDB is waiting for you to type in a command, like `run` or `help`. Use the ‘`help`’ command to get a list of all the commands to use, or see Debugging with GDB in the GNUPro Debugging Tools for a complete description of GDB and how to use it.
If your program crashes and you’re trying to determine why it crashed, the best thing to do is type `run` and let your program run. After it crashes, you can use the ‘`where`’ command to determine where it crashed, or ‘`info locals`’ to see the values of all the local variables. There’s also the ‘`print`’ declaration that lets you examine individual variables or what pointers point to. If your program is doing something unexpected, you can use the ‘`break`’ command to tell GDB to stop your program when it gets to a specific function or line number.

>     (gdb) break my_function

>     (gdb) break 47

Now, using the ‘`run`’ command, your program will stop at that breakpoint, and you can use the other GDB commands to look at the state of your program at that point, to modify variables, and to step through your program’s statements one at a time.

###### NOTE:

Specify additional arguments to the ‘`run`’ command to provide command-line arguments to your program. These previous example’s case and the next example’s case are the same as far as your program is concerned:

>     myprog -t foo --queue 47

>     gdb myprog

>     (gdb) run -t foo --queue 47

### Building and using DLLs with Cygwin

The following documentation discusses building and using dynamically linked libraries (DLLs) with Cygwin.

- Building DLLs
- Linking against DLLs

DLLs are linked into your program at run time instead of build time. There are three parts to a DLL:

- exports
A list of functions and variables that the `.dll` file makes available to other programs, as a list of global symbols, with the rest of the contents hidden. Normally, you’d create this list by hand with a text editor;however, it’s possible to do it automatically from the list of functions in your code. The `dlltool` program creates the exports section of the `.dll` file from your text file of exported symbols.
- code and data
The parts you write: functions, variables, etc. All these are merged together, for instance, for building one big object file and linking it to a `.dll` file. They are not put into your `.exe` at all.
- import library
The import library is a regular UNIX-like `.a` library, but it only contains the tiny bit of information needed to tell the operating system how your program interacts with (or imports) the `.dll` as data. This information is linked into your `.exe` file. This is also generated by the ‘`dlltool`’ utility.

#### Building DLLs

The following documentation provides a simple example of how to build a `.dll` file, using a single file, `myprog.c`, for the program, `myprog.exe` , and a single file, `mydll.c`, for the contents of the `.dll` file, `mydll.dll`, then compiling everything as objects.

>     gcc -c myprog.c

>     gcc -c mydll.c

Unfortunately, the process for building a .dll file is rather complicated with five run commands, like the following example’s declaration.

>     ld --dll -o mydll.dll mydll.o -e _mydll_init@12 --base-file mydll.base

>     dlltool --base-file=mydll.base --def mydll.def --output-exp mydll.exp --dllname                                                                   \mydll.dll

>     ld --dll -o mydll.dll mydll.o -e _mydll_init@12 --base-file mydll.base mydll.exp

>     dlltool --base-file=mydll.base --def mydll.def --output-exp mydll.exp --dllname                                                                      \mydll.dll

>     ld --dll -o mydll.dll mydll.o -e _mydll_init@12 mydll.exp

The extra steps give dlltool the opportunity to generate the extra sections (exports and relocation) that a `.dll` file needs. After this, you build the import library with the following commands such as the following example’s decalaration.

>     dlltool --def mydll.def --dllname mydll.dll --output-lib mydll.a

Now, when you build your program, you link against the import library, with declaration’s like the following example’s commands.

>     gcc -o myprog myprog.o mydll.a

###### NOTE:

This usage linked with `-e _rdll_init@12`, telling the operating system what the DLL’s entry point is, a special function that coordinates bringing the `.dll` file to life within the operating system. The minimum function looks like the following example’s declaration.

>     #include <windows.h>

>     int WINAPI

>     rdll_init(HANDLE h, DWORD reason, void *foo)

>     {

>        return 1;

>     }

#### Linking against DLLs

If you have an existing DLL already, you need to build a Cygwin-compatible import library to link. Unfortunately, there is not yet any tool to do this automatically. However, you can get most of the way by creating a `.def` file with these commands (use a bash shell for the quoting to work properly with such linking).

>     echo EXPORTS > foo.def

>     nm foo.dll | grep’ T _’ | sed’s/.* T _//’ >> foo.def

Once you have the `.def` file, you can create an import library from it, using a declaration similar to the following example’s form.

>     dlltool --def foo.def --dllname foo.dll --output-lib foo.a

### Defining Windows resources for Cygwin

`windres` reads a Windows resource file (`*.rc` ) and converts it to a res or coff file. The syntax and semantics of the input file are the same as for any other resource compiler; see any publication describing the Windows resource format for details. Also, see the `windres` documentation in Using `binutils` in GNUPro Utilities. The following example shows the usage of `windres` in a project:

>     myapp.exe : myapp.o myapp.res

>                           gcc -mwindows myapp.o myapp.res -o $@

>     myapp.res : myapp.rc resource.h

>                               windres $< -O coff -o $@

What follows is a quick-reference to the syntax that `windres` supports.

>     id ACCELERATORS suboptions

>     BEG

>     "^C" 12

>     "Q" 12

>     65 12

>     65 12, VIRTKEY ASCII NOINVERT SHIFT CONTROL ALT

>     65 12, VIRTKEY, ASCII, NOINVERT, SHIFT, CONTROL, ALT

>     (12 is an acc_id)

>     END

>     SHIFT, CONTROL, ALT require VIRTKEY

>     id BITMAP memflags "filename"

>     memflags defaults to MOVEABLE

>     id CURSOR memflags "filename"

>     memflags defaults to MOVEABLE,DISCARDABLE

>     id DIALOG memflags exstyle x,y,width,height styles BEG controls END

>     id DIALOGEX memflags exstyle x,y,width,height styles BEG controls END

>     id DIALOGEX memflags exstyle x,y,width,height,helpid styles BEG controls END

>     memflags defaults to MOVEABLE

>     exstyle may be EXSTYLE=number

>     styles: CAPTION "string"

>             CLASS id

>             STYLE FOO | NOT FOO | (12)

>             EXSTYLE number

>             FONT number, "name"

>             FONT number, "name",weight,italic

>             MENU id

>             CHARACTERISTICS number

>             LANGUAGE number,number

>             VERSIONK number

>     controls:

>             AUTO3STATE params

>             AUTOCHECKBOX params

>             AUTORADIOBUTTON params

>             BEDIT params

>             CHECKBOX params

>             COMBOBOX params

>             CONTROL ["name",] id, class, style, x,y,w,h [,exstyle] [data]

>             CONTROL ["name",] id, class, style, x,y,w,h, exstyle, helpid [data]

>              CTEXT params

>             DEFPUSHBUTTON params

>             EDITTEXT params

>             GROUPBOX params

>             HEDIT params

>             ICON ["name",] id, x,y [data]

>             ICON ["name",] id, x,y,w,h, style, exstyle [data]

>             ICON ["name",] id, x,y,w,h, style, exstyle, helpid [data]

>             IEDIT params

>             LISTBOX params

>             LTEXT params

>             PUSHBOX params

>             PUSHBUTTON params

>             RADIOBUTTON params

>             RTEXT params

>             SCROLLBAR params

>             STATE3 params

>             USERBUTTON "string", id, x,y,w,h, style, exstyle

>     params:

>             ["name",] id, x, y, w, h, [data]

>             ["name",] id, x, y, w, h, style [,exstyle] [data]

>             ["name",] id, x, y, w, h, style, exstyle, helpid [data]

>     [data] is optional BEG (string|number) [,(string|number)] (etc) END

>     id FONT memflags "filename"

>     memflags defaults to MOVEABLE|DISCARDABLE

>     id ICON memflags "filename"

>     memflags defaults to MOVEABLE|DISCARDABLE

>     LANGUAGE num,num

>     id MENU options BEG items END

>     items:

>             "string", id, flags:

>             SEPARATOR:

>             POPUP "string" flags BEG menuitems END

>     flags::

>             CHECKED:

>              GRAYED:

>              HELP:

>              INACTIVE:

>              MENUBARBREAK:

>              MENUBREAK

>     id MENUEX suboptions BEG items END

>     items::

>              MENUITEM "string":

>              MENUITEM "string", id:

>              MENUITEM "string", id, type [,state]:

>              POPUP "string" BEG items END:

>              POPUP "string", id BEG items END:

>              POPUP "string", id, type BEG items END:

>              POPUP "string", id, type, state [,helpid] BEG items END

>     memflags defaults to MOVEABLE

>     id RCDATA suboptions BEG (string|number) [,(string|number)] (etc) END

>     STRINGTABLE suboptions BEG strings END

>     strings::

>              id "string":

>              id, "string"

>     (User data)

>     id id suboptions BEG (string|number) [,(string|number)] (etc) END

>     id VERSIONINFO stuffs BEG verblocks END

>     stuffs: FILEVERSION num,num,num,num:

>              PRODUCTVERSION num,num,num,num:

>              FILEFLAGSMASK num:

>              FILEOS num:

>              FILETYPE num:

>              FILESUBTYPE num:

>     verblocks::

>              BLOCK "StringFileInfo" BEG BLOCK BEG vervals END END:

>              BLOCK "VarFileInfo" BEG BLOCK BEG vertrans END END

>     vervals: VALUE "foo","bar"

>     vertrans: VALUE num,num

>     suboptions::

>              memflags:

>              CHARACTERISTICS num:

>              LANGUAGE num,num:

>              VERSIONK num

>     memflags are MOVEABLE/FIXED PURE/IMPURE PRELOAD/LOADONCALL DISCARDABLE

### Cygwin utilities

Cygwin comes with a number of command-line utilities for managing the UNIX emulation portion of the Cygwin environment. While many of these reflect their UNIX counterparts, each was written specifically for Cygwin. See the corresponding documentation to the following Cygwin utilities.

- `cygcheck`
- `cygpath`
- `kill`
- `mkgroup`
- `mkpasswd`
- `mount`
- `ps`
- `umount`

### Cygwin functions

The following documentation discusses the Cygwin functions.

- `cygwin_attach_handle_to_fd`
- `cygwin_conv_to_full_posix_path`
- `cygwin_conv_to_posix_path`
- `cygwin_conv_to_full_win32_path`
- `cygwin_conv_to_win32_path`
- `cygwin_detach_dll`
- `cygwin_getshared`
- `cygwin_internal`
- `cygwin_posix_path_list_p`
- `cygwin_posix_to_win32_path_list`
- `cygwin_posix_to_win32_path_list_buf_size`
- `cygwin_split_path`
- `cygwin_win32_to_posix_path_list`
- `cygwin_win32_to_posix_path_list_buf_size`
- `cygwin_winpid_to_pid`

These functions are specific to Cygwin itself, and probably will not have relations to any other library or standards.

Top|Contents|Index|Previous|Next